home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 60.zip / BS1 part 60 / LSD 28.adf / ARexx.Guide.pp / ARexx.Guide (.txt)
Amigaguide Document  |  1990-09-07  |  19KB  |  419 lines
  1.              /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\
  2.              /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\
  3.              /~~\___________________________________________/~~\
  4.              /~~\___________________________________________/~~\
  5.              /~~\__/~~\__________/~~~~~~~~\___/~~~~~~~~~\___/~~\
  6.              /~~\__/~~\_________/~~~~~~~~~~___/~~~~~~~~~~\__/~~\
  7.              /~~\__/~~\_________/~~\__________/~~\____/~~\__/~~\
  8.              /~~\__/~~\_________/~~\__________/~~\____/~~\__/~~\
  9.              /~~\__/~~\_________/~~~~~~~~~\___/~~\____/~~\__/~~\
  10.              /~~\__/~~\__________/~~~~~~~~~\__/~~\____/~~\__/~~\
  11.              /~~\__/~~\_________________/~~\__/~~\____/~~\__/~~\
  12.              /~~\__/~~\_________________/~~\__/~~\____/~~\__/~~\
  13.              /~~\__/~~~~~~~~~\__/~~~~~~~~~~\__/~~~~~~~~~~\__/~~\
  14.              /~~\___/~~~~~~~~\___/~~~~~~~~\___/~~~~~~~~~\___/~~\
  15.              /~~\___________________________________________/~~\
  16.              /~~\________________________________________mUb/~~\
  17.              /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\
  18.              /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\
  19.                                    present
  20.                                an ARexx Guide
  21.                           ripped to you by mUb/LSD
  22. Flow of control
  23. [I] BREAK     : BREAK
  24. Exit from innermost DO-END block or INTERPRET instruction
  25. [I] DO        : DO
  26.                 DO FOREVER
  27.                 DO [FOR] count
  28.                 DO WHILE/UNTIL test
  29.                 DO var=start [TO limit] [BY step]
  30.                 DO [FOR] count WHILE/UNTIL test
  31.                 DO var=start [TO limit] [BY step] FOR count
  32.                 DO var=start [TO limit] [BY step] WHILE/UNTIL test
  33.                 DO var=start [TO limit] [BY step] FOR count WHILE/UNTIL test
  34. Begin a block of instructions or a loop
  35. [I] ELSE      : ELSE [;] instruction
  36. Introduce code to be executed when an IF test fails
  37. [I] END       : END [var]
  38. Terminate a block of instructions beginning with DO or SELECT
  39. [I] EXIT      : EXIT [expr]
  40. Terminate a script
  41. [I] IF        : IF test [;] THEN [;] instruction [ELSE [;] instruction]
  42. Introduce code to be executed if test expression is True
  43. [I] INTERPRET : INTERPRET [expr]
  44. Execute ARexx instructions contained in a string
  45. [I] ITERATE   : ITERATE [var]
  46. Skip to the end of the current iterative loop
  47. [I] LEAVE     : LEAVE [var]
  48. Break out of current iterative loop
  49. [I] NOP       : NOP
  50. Do nothing - a dummy instruction
  51. [I] OTHERWISE : OTHERWISE [;] [instruction(s)]
  52. Introduce default case for SELECT control structure
  53. [I] SELECT    : SELECT; WHEN ... [OTHERWISE [;] [instructions]] END
  54. Branch to first case whose controlling condition is met
  55. [I] SIGNAL    : SIGNAL ON type
  56.                 SIGNAL OFF type
  57.                 SIGNAL [VALUE] label-expression
  58. Turn interrupt type on/off; transfer control to label
  59. [I] THEN      : THEN [;] instruction
  60. Execute dependent instruction if preceding expression was True
  61. [I] WHEN      : WHEN test [;] THEN [;] instruction
  62. In SELECT, introduce code to be executed if test is True
  63. Functions and arguments
  64. [I] ARG       : ARG [template] [,template ...]
  65. Shorthand form of PARSE UPPER ARG
  66. [F] ARG       : numargs = ARG()
  67.                 argn    = ARG(num)
  68.                 bool    = ARG(num, mode)
  69. Return information about script or function arguments
  70. Modes:   E - Exists          O - Omitted
  71. [I] CALL      : CALL function(arg, arg, arg)
  72.                 CALL function arg, arg, arg
  73. Invoke a function but ignore the result
  74. [I] PROCEDURE : PROCEDURE [EXPOSE var [var ...]]
  75. Protect function caller's variables from name collisions
  76. [I] RETURN    : RETURN [expr]
  77. Return control (and optionally a value) to caller
  78. Strings (editing)
  79. [F] COMPRESS  : s = COMPRESS(str, [list])
  80. Remove the characters in list (default=space) from str
  81. [F] DELSTR    : s = DELSTR(str, start, [len])
  82. Delete len (default=rest of str) characters from str, from start
  83. [F] INSERT    : s = insert(istr,str,[start],[len],[pad])
  84. Insert len characters of istr into str at start
  85. [F] OVERLAY   : s = OVERLAY(new, old, [start], [len], [pad])
  86. Overlay len characters of new on old, from start
  87. [F] STRIP     : s = STRIP(str, [mode], [list])
  88. Strip leading and/or trailing characters in list from str
  89. Modes:   B - Both (default)   L - Leading  T - Trailing
  90. [F] SUBSTR    : s = SUBSTR(str, start, [len],[pad])
  91. Extract len (default=rest of str) characters of str, from start
  92. [F] TRANSLATE : s = TRANSLATE(str)
  93.                 s = TRANSLATE(str,[output],[input],[pad])
  94. Translate str using input and output character tables
  95. [F] TRIM      : s = TRIM(str)
  96. Remove trailing blanks from str
  97. [I] UPPER     : UPPER var [var ...]
  98. Convert contents of variables to upper case
  99. [F] UPPER     : s = UPPER(str)
  100. Convert str to upper case
  101. Strings (pattern matching)
  102. [F] ABBREV    : bool = ABBREV(str, abbr, [len])
  103. Test if abbr is an abbreviation of str with at least len characters
  104. [F] COMPARE   : n = COMPARE(str1, str2, [pad])
  105. Determine position at which strings differ (0 if identical)
  106. [F] INDEX     : n = INDEX(str,pat,[start])
  107. Return position of pat in str, from 1 or start (0 if not found)
  108. [F] LASTPOS   : n = LASTPOS(pat,str,[start])
  109. Return position of pat in str, searching backwards from end or start
  110. [F] POS       : n = POS(pat,str,[start])
  111. Return position of pat in str, from 1 or start (0 if found)
  112. [F] VERIFY    : n = VERIFY(str,list,[match],[start])
  113. Search str from 1 or start for characters in list; return index or 0
  114. Modes (match) : M - Return index of first list character of str
  115.     Other/default - Return index of first non-list character
  116. Strings (formatting)
  117. [F] CENTER    : s = CENTER(str, width, [pad])
  118. Center str in a field of given width
  119. [F] LEFT      : s = LEFT(str,count,[pad])
  120. Extract leftmost count characters of str, pad on right if needed
  121. [F] REVERSE   : s = REVERSE(str)
  122. Reverse str
  123. [F] RIGHT     : s = RIGHT(str,width,[pad])
  124. Extract rightmost width characters of str, pad on left if needed
  125. [F] SPACE     : s = SPACE(str, [len], [pad])
  126. Set word-breaks in str to len spaces (or pad)
  127. Strings (word-oriented)
  128. [F] DELWORD   : s = DELWORD(str, start, [len])
  129. Delete len words from str, beginning at start word
  130. [F] FIND      : n = FIND(str, phrase)
  131. Return position of word-string phrase in str
  132. [F] SUBWORD   : s = SUBWORD(str, start, [count])
  133. Extract count words (default=rest of str) from str, from start word
  134. [F] WORD      : s = WORD(str,n)
  135. Extract word n from str
  136. [F] WORDINDEX : n = WORDINDEX(str,n)
  137. Determine character position in str of start of word n
  138. [F] WORDLENGTH: n = WORDLENGTH(str,n)
  139. Determine length of word n in str
  140. [F] WORDS     : n = WORDS(str)
  141. Return number of words in str
  142. Strings (miscellaneous)
  143. [F] COPIES    : s = COPIES(str, n)
  144. Concatenate n copies of str
  145. [F] HASH      : n = HASH(str)
  146. Calculate a hash value for str
  147. [F] LENGTH    : n = LENGTH(str)
  148. Return length of str in characters
  149. [I] PARSE       : PARSE [UPPER] source [template] [,template]
  150.       Source name          Source string contents
  151.          ARG                  Arguments to script or function
  152.          EXTERNAL             Input via STDERR file
  153.          NUMERIC              NUMERIC options: digits fuzz form
  154.          PULL                 Input via STDIN file
  155.          SOURCE               type result called resolved ext host
  156.          VALUE expr WITH      Result of expression
  157.          VAR varname          Contents of varname
  158.          VERSION              version cpu mpu video freq
  159. Split input string(s) into substrings
  160. [F] XRANGE      : s = XRANGE([c1],[c2])
  161. Build character string from c1 to c2 with consecutive ASCII values
  162. Numbers
  163. [F] ABS         : absval = ABS(num)
  164. Return absolute value of numeric expression
  165. [F] DIGITS      : n = DIGITS()
  166. Return current NUMERIC DIGITS setting
  167. [F] FORM        : f = FORM()
  168. Return current NUMERIC FORM setting
  169. [F] FUZZ        : f = FUZZ()
  170. Return current NUMERIC FUZZ setting
  171. [F] MAX         : n = MAX(n1, n2 [, n3 ...])
  172. Find the largest of a set of numbers
  173. [F] MIN         : n = MIN(n1, n2 [, n3 ...])
  174. Find the smallest of a set of numbers
  175. [I] NUMERIC     : NUMERIC DIGITS num
  176.                   NUMERIC FUZZ   num
  177.                   NUMERIC FORM SCIENTIFIC
  178.                   NUMERIC FORM ENGINEERING
  179. Set numeric calculation and display options
  180. [F] RANDOM      : n = RANDOM([low],[high],[seed])
  181. Return pseudo-random integer between low and high inclusive
  182. [F] RANDU       : n = RANDU([seed])
  183. Return pseudo-random number between 0 and 1
  184. [F] SIGN        : n = SIGN(num)
  185. Determine the sign of a number, return -1, 0, or 1
  186. [F] TRUNC       : n = TRUNC(number,[places])
  187. Truncate number to places decimal places
  188. Bit manipulation
  189. [F] BITAND      : s = BITAND(str1, [str2], [pad])
  190. Return bit-wise AND of two strings, padded to equal length
  191. [F] BITCHG      : s = BITCHG(str, n)
  192. Invert bit n, counting from right, in str
  193. [F] BITCLR      : s = BITCLR(str, n)
  194. Clear bit n, counting from right, in str
  195. [F] BITCOMP     : n = BITCOMP(str1, str2, [pad])
  196. Return first bit, counting from right, at which str1 ~= str2 (-1 if equal)
  197. [F] BITOR       : s = BITOR(str1, [str2], [pad])
  198. Return bit-wise OR of two strings, padded to equal length
  199. [F] BITSET      : s = BITSET(str, n)
  200. Set bit n, counting from right in str
  201. [F] BITTST      : bool = BITTST(str, n)
  202. Test bit n, counting from right, in str
  203. [F] BITXOR      : s = BITXOR(str1, [str2], [pad])
  204. Return bit-wise exclusive-OR of two strings, padded to equal length
  205. Data conversion
  206. [F] B2C         : s = B2C(binstr)
  207. Return character equivalent of binary string
  208. [F] C2B         : b = C2B(str)
  209. Return binary digit string equivalent to character string
  210. [F] C2D         : n = C2D(str, [len])
  211. Return integer number corresponding to string (of len bytes)
  212. [F] C2X         : h = C2X(str)
  213. Return hexadecimal number corresponding to string
  214. [F] D2C         : s = D2C(num,[count])
  215. Return string equivalent, count bytes long, of num
  216. [F] D2X         : h = D2X(num,[count])
  217. Return hexadecimal string, count bytes long, equivalent to num
  218. [F] X2C         : s = X2C(hex)
  219. Return character equivalent of hex string
  220. [F] X2D         : n = X2D(hex,[n])
  221. Convert n rightmost digits (or all) of hex string to decimal
  222. Values and variables
  223. [F] DATATYPE  : type = DATATYPE(str)
  224.                 bool = DATATYPE(str,mode)
  225. Test attributes of string (type = `NUM' or `CHAR')
  226. Modes:   A - Alphanumeric  B - Binary        L - Lower case
  227.          M - Mixed case    N - Numeric       S - Symbol
  228.          U - Upper case    W - Whole number  X - Hexadecimal
  229. [I] DROP      : DROP var [var ...]
  230. Restore a variable to its uninitialized state
  231. [F] SYMBOL    : s = SUBWORD(str)
  232. Determine if a string is a valid ARexx symbol
  233. [F] VALUE     : val = VALUE(str)
  234. Treating str as an ARexx symbol, return its value
  235. Console input/output
  236. [I] ECHO      : ECHO expr
  237. Send the expression result to the standard output
  238. [F] LINES     : n = LINES([file])
  239. Return number of lines queued for interactive stream
  240. [I] PULL      : PULL [template] [,template ...]
  241. Shorthand form of PARSE UPPER PULL
  242. [I] PUSH      : PUSH expr
  243. Pre-load the standard input in `last-in, first-out' order
  244. [I] QUEUE     : QUEUE expr
  245. Pre-load the standard input in `first-in, first-out' order
  246. [I] SAY       : SAY [expr]
  247. Send expression result to standard output (usually console)
  248. File input/output
  249. [F] CLOSE     : bool = CLOSE(file)
  250. Close the file with the given identifier
  251. [F] EOF       : bool = EOF(file)
  252. Return 1 if end of file has been detected; else 0
  253. [F] OPEN      : bool = OPEN(file, name, [mode])
  254. Open a file called name in given mode
  255. Modes: R - Read (default)   W - Write (create)   A - Append
  256. [F] READCH    : s = READCH(file, [count])
  257. Return count characters from file
  258. [F] READLN    : s = READLN(file)
  259. Return a line from file as a string
  260. [F] SEEK      : n = SEEK(file,offset,[mode])
  261. Move file position to offset according to mode
  262. Modes: C - Current (default)  B - Beginning  E - End
  263. [F] WRITECH   : n = WRITECH(file, str)
  264. Write str to file, return count written
  265. [F] WRITELN   : n = WRITELN(file, str)
  266. Write str plus linefeed to file, return count written
  267. Files
  268. [S] DELETE    : bool = DELETE(name)
  269. Delete a file or directory
  270. [F] EXISTS    : bool = EXISTS(name)
  271. Return True if given file or directory exists
  272. [S] MAKEDIR   : bool = MAKEDIR(dirname)
  273. Create a directory of the given name
  274. [S] RENAME    : bool = RENAME(oldname, newname)
  275. Rename a file or directory
  276. [S] SHOWDIR   : filelist = SHOWDIR(dir, [mode], [pad])
  277. List the file and/or directory names in a directory
  278. Modes: A - All (default)    F - Files only  D - Directories only
  279. [S] STATEF    : filestring = STATEF(pathname)
  280. Obtain information about a file or directory
  281. Format: type size blk bits day min tick com
  282. Script environment
  283. [F] DATE      : d = DATE([outmode],[indate],[inmode])
  284. Find today's date, or info about a specified date
  285. Modes:   B - Base (days since 01/01/0000)
  286.          C - Century (days this century)
  287.          D - Days (days since start of year, counting today)
  288.          E - European (dd/mm/yy - e.g. 19/11/76)
  289.          I - Internal (days since 01/01/1978)
  290.          J - Julian (yyddd - 2-digit year, 3-digit days this year)
  291.          M - Month name in English mixed case (e.g. `November')
  292.          N - Normal, the default (dd mmm yyyy, e.g. 01 Jun 1986)
  293.          O - Ordered (yy/mm/dd, e.g. 84/05/24)
  294.          S - Standard (yyyymmdd, e.g. 19921005)
  295.          U - USA (mm/dd/yy, 12/21/88)
  296.          W - Weekday name in English mixed case (e.g. `Thursday')
  297. [F] ERRORTEXT : text = ERRORTEXT(n)
  298. Return a description of syntax error number n
  299. [I] OPTIONS   : OPTIONS
  300.                 OPTIONS [NO] RESULTS
  301.                 OPTIONS [NO] CACHE
  302.                 OPTIONS PROMPT [expr]
  303.                 OPTIONS FAILAT expr
  304. Set script options
  305. [F] SOURCELINE: n = SOURCELINE()
  306.                 s = SOURCELINE(num)
  307. Read count of source lines, or line num from current script
  308. [F] TIME      : t = TIME([mode])
  309. Find current or elapsed time
  310. Modes:   C - Civil (h:mmAM or h:mmPM, e.g. 3:07AM)
  311.          E - Elapsed (s.cc, seconds and hundredths, in interval)
  312.          H - Completed hours since midnight (e.g. 4)
  313.          M - Completed minutes since midnight (e.g. 243)
  314.          N - Normal, the default (hh:mm:ss, e.g. 17:04:41)
  315.          R - Same as elapsed, but resets timer to 0.00
  316.          S - Completed seconds since midnight (e.g. 17353)
  317. [I] TRACE     : TRACE mode
  318.                 TRACE [VALUE] expr
  319.                 TRACE num
  320. Set tracing mode
  321. Modes:   A - All clauses  B - Background     C - Commands
  322.          E - Errors       I - Intermediates  L - Labels
  323.          N - Normal       O - Off            R - Results
  324.          S - Scan
  325. Special features: ? - Interactive         +num - skip interactive pauses
  326.                   ! - Command inhibition  -num - trace suppression count
  327. [F] TRACE     : t = TRACE([mode])
  328. Get/set tracing mode (see modes under TRACE instruction)
  329. ARexx environment
  330. [F] ADDLIB    : ADDLIB(name, pri, [offset, version])
  331. Add function library/host name to library list
  332. [I] ADDRESS   : ADDRESS
  333.                 ADDRESS name
  334.                 ADDRESS VALUE name-expression
  335.                 ADDRESS name command-expression
  336. Modify host address; send command to a host
  337. [F] ADDRESS   : host = ADDRESS()
  338. Return host address string
  339. [F] FREESPACE : n = FREESPACE()
  340.                 n = FREESPACE(addr, size)
  341. Return size bytes of memory at addr to ARexx's internal memory pool
  342. [F] GETCLIP   : s = GETCLIP(clip)
  343. Return value string associated with clip name
  344. [F] GETSPACE  : addr = GETSPACE(size)
  345. Allocate size bytes of memory in ARexx's internal memory pool
  346. [F] REMLIB    : bool = REMLIB(name)
  347. Remove an entry from the Library List
  348. [F] SETCLIP   : bool = SETCLIP(name, [value])
  349. Set string value for clip name (remove name if value omitted)
  350. [I] SHELL     : SHELL
  351.                 SHELL name
  352.                 SHELL VALUE name-expression
  353.                 SHELL name command-expression
  354. Modify host address; send command to a host
  355. [F] SHOW      : s    = SHOW(mode,,[pad])
  356.                 bool = SHOW(mode,name)
  357. Return information about a resource
  358. Modes:   C - Clips               F - Files        I - Internal ports
  359.          L - Function Libraries  P - Public ports
  360. Messages, packets and ports
  361. [S] CLOSEPORT : bool = CLOSEPORT(portname)
  362. Close a message port opened with OPENPORT
  363. [S] GETARG    : arg = GETARG(packet, [whicharg])
  364. Obtain an argument string from a message packet
  365. [S] GETPKT    : pkt = GETPKT(portname)
  366. Pick up a message packet from a message port
  367. [S] OPENPORT  : bool = OPENPORT(portname)
  368. Open a public message port with the given name
  369. [S] REPLY     : 1 = REPLY(pkt, [result], [result2])
  370. Return a message packet to its sender, default results = 0, 0
  371. [S] TYPEPKT   : cmd   = TYPEPKT(pkt)
  372.                 count = TYPEPKT(pkt,'a')
  373.                 bool  = TYPEPKT(pkt,mode)
  374. Extract information from a message packet
  375. Modes: F - Function    C - Command
  376. [S] WAITPKT   : bool = WAITPKT(portname)
  377. Wait for a message packet to arrive at a port
  378. Operating system
  379. [S] ALLOCMEM  : mem = ALLOCMEM(size, [type])
  380. Allocate size bytes of system memory, with type attributes
  381. [S] BADDR     : addr = BADDR(bptr)
  382. Convert BPTR to address
  383. [S] DELAY     : 0 = DELAY(n)
  384. Pause for n 50ths of a second
  385. [F] EXPORT    : count = EXPORT(addr,[str],[len],[pad])
  386. Copy len bytes of str to memory at addr
  387. [S] FORBID    : count = FORBID()
  388. Turn off multitasking
  389. [S] FREEMEM   : 1 = FREEMEM(addr, size)
  390. Free size bytes of memory at addr allocated by ALLOCMEM
  391. [F] IMPORT    : s = IMPORT(addr,[len])
  392. Return contents of len bytes (or 0-terminated) memory at addr
  393. [S] NEXT      : value = NEXT(addr,[offset])
  394. Return the 4-byte value stored at addr + offset
  395. [S] NULL      : '00000000'x = NULL()
  396. Return a 4-byte string corresponding to a null address
  397. [S] OFFSET    : addr = OFFSET(addr,amount)
  398. Return the address addr + amount
  399. [S] PERMIT    : count = PERMIT()
  400. Re-enable multitasking after FORBID
  401. [F] PRAGMA    :   oldcd = PRAGMA('d', [newcd]) /* Current directory */
  402.                  oldpri = PRAGMA('p', newpri)  /* Task priority     */
  403.                 oldsize = PRAGMA('s', size)    /* Stack size        */
  404.                       1 = PRAGMA('w', [mode])  /* DOS requesters    */
  405.                      id = PRAGMA('i')          /* Task ID (address) */
  406.                    bool = PRAGMA('*', [file])  /* Console handler   */
  407. A grouping of system-specific facilities as one function
  408. [S] SHOWLIST  : list = SHOWLIST(mode,,[pad])
  409.                 bool = SHOWLIST(mode, name)
  410.                 addr = SHOWLIST(mode, name,, 'a')
  411. Return information about a shared system list
  412. Modes:   A - Assigns       D - Devices     H - Handlers
  413.          I - Interrupts    L - Libraries   M - Memory
  414.          P - Ports         R - Resources   S - Semaphore
  415.          T - Ready tasks   V - Volumes     W - Waiting tasks
  416. [F] STORAGE   : n = STORAGE()
  417.                 s = STORAGE(addr,[str],[len],[pad])
  418. Copy len bytes of str to memory at addr
  419.